// 定义包名
package flutter.plugins.contactsservice.contactsservice;

// 导入TargetApi注解，指定最低API级别
import android.annotation.TargetApi;
// 导入ContentProviderOperation，用于批量操作联系人数据
import android.content.ContentProviderOperation;
// 导入ContentResolver，用于访问Android内容提供者（如联系人数据库）
import android.content.ContentResolver;
// 导入ContentUris，用于构建内容URI
import android.content.ContentUris;
// 导入Context，Android应用上下文
import android.content.Context;
// 导入Intent，用于启动其他活动
import android.content.Intent;
// 导入Resources，用于访问应用资源
import android.content.res.Resources;
// 导入Cursor，用于操作数据库查询结果
import android.database.Cursor;
// 导入Bitmap相关类，用于处理联系人头像
import android.graphics.Bitmap;
import android.graphics.BitmapFactory;
// 导入Uri，用于标识数据位置
import android.net.Uri;
// 导入AsyncTask，用于执行异步任务
import android.os.AsyncTask;
// 导入Build，用于检查Android版本
import android.os.Build;
// 导入BaseColumns，用于访问基础列
import android.provider.BaseColumns;
// 导入ContactsContract，用于访问联系人数据
import android.provider.ContactsContract;
// 导入TextUtils，用于字符串处理
import android.text.TextUtils;
// 导入Log，用于日志记录
import android.util.Log;

// 导入IO相关类，用于处理流操作
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
// 导入集合类，用于存储数据
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.LinkedHashMap;
// 导入并发相关类，用于线程池管理
import java.util.concurrent.ArrayBlockingQueue;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;

// 导入Flutter相关类，用于插件开发
import io.flutter.embedding.engine.plugins.FlutterPlugin;
import io.flutter.embedding.engine.plugins.activity.ActivityAware;
import io.flutter.embedding.engine.plugins.activity.ActivityPluginBinding;
import io.flutter.plugin.common.BinaryMessenger;
import io.flutter.plugin.common.MethodCall;
import io.flutter.plugin.common.MethodChannel;
import io.flutter.plugin.common.MethodChannel.MethodCallHandler;
import io.flutter.plugin.common.MethodChannel.Result;
import io.flutter.plugin.common.PluginRegistry;
import io.flutter.plugin.common.PluginRegistry.Registrar;

// 静态导入常量和类，简化代码
import static android.app.Activity.RESULT_CANCELED;
import static android.provider.ContactsContract.CommonDataKinds;
import static android.provider.ContactsContract.CommonDataKinds.Email;
import static android.provider.ContactsContract.CommonDataKinds.Organization;
import static android.provider.ContactsContract.CommonDataKinds.Phone;
import static android.provider.ContactsContract.CommonDataKinds.StructuredName;
import static android.provider.ContactsContract.CommonDataKinds.StructuredPostal;

/**
 * 该注解指定此代码适用于Android 2.1 (ECLAIR)及以上版本
 * 确保代码在较旧设备上不会出现兼容性问题
 */
@TargetApi(Build.VERSION_CODES.ECLAIR)

/**
 * Flutter联系人服务插件的主类
 * 实现了MethodCallHandler接口处理Flutter端调用
 * 实现了FlutterPlugin接口管理插件生命周期
 * 实现了ActivityAware接口处理Activity相关事件
 */
public class ContactsServicePlugin implements MethodCallHandler, FlutterPlugin, ActivityAware {

  // 常量定义：表单操作被用户取消
  private static final int FORM_OPERATION_CANCELED = 1;
  // 常量定义：无法打开表单
  private static final int FORM_COULD_NOT_BE_OPEN = 2;

  // 日志标签，用于在Logcat中标识此插件的日志
  private static final String LOG_TAG = "flutter_contacts";
  // ContentResolver实例，用于访问联系人数据库
  private ContentResolver contentResolver;
  // MethodChannel实例，用于与Flutter端通信
  private MethodChannel methodChannel;
  // 代理实例，用于处理需要Activity上下文的操作
  private BaseContactsServiceDelegate delegate;
  // Resources实例，用于访问Android资源
  private Resources resources;

  // 线程池，用于执行异步任务
  // 核心线程数为0，最大线程数为10，线程空闲60秒后回收
  // 使用有界队列（容量1000）存储待执行任务
  private final ExecutorService executor =
          new ThreadPoolExecutor(0, 10, 60, TimeUnit.SECONDS, new ArrayBlockingQueue<Runnable>(1000));

  /**
   * 初始化旧版代理（用于兼容旧版Flutter引擎）
   * @param registrar 插件注册器
   */
  private void initDelegateWithRegister(Registrar registrar) {
    this.delegate = new ContactServiceDelegateOld(registrar);
  }

  /**
   * 静态注册方法（旧版Flutter引擎使用）
   * @param registrar 插件注册器
   */
  public static void registerWith(Registrar registrar) {
    // 创建插件实例
    ContactsServicePlugin instance = new ContactsServicePlugin();
    // 初始化插件实例
    instance.initInstance(registrar.messenger(), registrar.context());
    // 初始化代理
    instance.initDelegateWithRegister(registrar);
  }

  /**
   * 初始化插件实例
   * @param messenger 二进制消息传递器，用于创建MethodChannel
   * @param context Android上下文
   */
  private void initInstance(BinaryMessenger messenger, Context context) {
    // 创建MethodChannel，用于与Flutter端通信
    // 通道名称为："github.com/clovisnicolas/flutter_contacts"
    methodChannel = new MethodChannel(messenger, "github.com/clovisnicolas/flutter_contacts");
    // 设置此对象为方法调用处理器
    methodChannel.setMethodCallHandler(this);
    // 获取ContentResolver实例
    this.contentResolver = context.getContentResolver();
  }

  /**
   * 当插件附加到Flutter引擎时调用（新版Flutter引擎）
   * @param binding Flutter插件绑定
   */
  @Override
  public void onAttachedToEngine(FlutterPluginBinding binding) {
    // 获取应用资源
    resources = binding.getApplicationContext().getResources();
    // 初始化插件实例
    initInstance(binding.getBinaryMessenger(), binding.getApplicationContext());
    // 创建新版代理实例
    this.delegate = new ContactServiceDelegate(binding.getApplicationContext());
  }

  /**
   * 当插件从Flutter引擎分离时调用
   * @param binding Flutter插件绑定
   */
  @Override
  public void onDetachedFromEngine(FlutterPluginBinding binding) {
    // 清除方法调用处理器
    methodChannel.setMethodCallHandler(null);
    // 释放资源
    methodChannel = null;
    contentResolver = null;
    this.delegate = null;
    resources = null;
  }

  /**
   * 处理来自Flutter端的方法调用
   * @param call 方法调用对象，包含方法名和参数
   * @param result 结果处理器，用于返回结果给Flutter端
   */
  @Override
  public void onMethodCall(MethodCall call, Result result) {
    // 根据方法名分发处理
    switch(call.method){
      // 获取联系人列表
      case "getContacts": {
        this.getContacts(
                call.method,
                (String)call.argument("query"),
                (boolean)call.argument("withThumbnails"),
                (boolean)call.argument("photoHighResolution"),
                (boolean)call.argument("orderByGivenName"),
                (boolean)call.argument("androidLocalizedLabels"),
                result
        );
        break;
      }
      // 根据电话号码获取联系人
      case "getContactsForPhone": {
        this.getContactsForPhone(
                call.method,
                (String)call.argument("phone"),
                (boolean)call.argument("withThumbnails"),
                (boolean)call.argument("photoHighResolution"),
                (boolean)call.argument("orderByGivenName"),
                (boolean)call.argument("androidLocalizedLabels"),
                result
        );
        break;
      }
      // 根据邮箱获取联系人
      case "getContactsForEmail": {
        this.getContactsForEmail(
                call.method,
                (String)call.argument("email"),
                (boolean)call.argument("withThumbnails"),
                (boolean)call.argument("photoHighResolution"),
                (boolean)call.argument("orderByGivenName"),
                (boolean)call.argument("androidLocalizedLabels"),
                result
        );
        break;
      }
      // 获取联系人头像
      case "getAvatar": {
        final Contact contact = Contact.fromMap((HashMap)call.argument("contact"));
        this.getAvatar(contact, (boolean)call.argument("photoHighResolution"), result);
        break;
      }
      // 添加联系人
      case "addContact": {
        final Contact contact = Contact.fromMap((HashMap)call.arguments);
        if (this.addContact(contact)) {
          result.success(null); // 添加成功
        } else {
          result.error(null, "Failed to add the contact", null); // 添加失败
        }
        break;
      }
      // 删除联系人
      case "deleteContact": {
        final Contact contact = Contact.fromMap((HashMap)call.arguments);
        if (this.deleteContact(contact)) {
          result.success(null); // 删除成功
        } else {
          result.error(null, "Failed to delete the contact, make sure it has a valid identifier", null); // 删除失败
        }
        break;
      }
      // 更新联系人
      case "updateContact": {
        final Contact contact = Contact.fromMap((HashMap)call.arguments);
        if (this.updateContact(contact)) {
          result.success(null); // 更新成功
        } else {
          result.error(null, "Failed to update the contact, make sure it has a valid identifier", null); // 更新失败
        }
        break;
      }
      // 打开现有联系人的编辑页面
      case "openExistingContact" :{
        final Contact contact = Contact.fromMap((HashMap)call.argument("contact"));
        final boolean localizedLabels = call.argument("androidLocalizedLabels");
        if (delegate != null) {
          delegate.setResult(result);
          delegate.setLocalizedLabels(localizedLabels);
          delegate.openExistingContact(contact);
        } else {
          result.success(FORM_COULD_NOT_BE_OPEN);
        }
        break;
      }
      // 打开新建联系人页面
      case "openContactForm": {
        final boolean localizedLabels = call.argument("androidLocalizedLabels");
        if (delegate != null) {
          delegate.setResult(result);
          delegate.setLocalizedLabels(localizedLabels);
          delegate.openContactForm();
        } else {
          result.success(FORM_COULD_NOT_BE_OPEN);
        }
        break;
      }
      // 打开设备联系人选择器
      case "openDeviceContactPicker": {
        final boolean localizedLabels = call.argument("androidLocalizedLabels");
        openDeviceContactPicker(result, localizedLabels);
        break;
      }
      // 未实现的方法
      default: {
        result.notImplemented();
        break;
      }
    }
  }

  /**
   * 定义查询联系人数据库时需要返回的字段
   * 这些字段涵盖了联系人的所有关键信息
   */
  private static final String[] PROJECTION =
          {
                  ContactsContract.Data.CONTACT_ID,               // 联系人ID
                  ContactsContract.Profile.DISPLAY_NAME,         // 显示名称
                  ContactsContract.Contacts.Data.MIMETYPE,       // 数据类型
                  ContactsContract.RawContacts.ACCOUNT_TYPE,      // 账户类型
                  ContactsContract.RawContacts.ACCOUNT_NAME,      // 账户名称
                  StructuredName.DISPLAY_NAME,                   // 结构化名称的显示名
                  StructuredName.GIVEN_NAME,                     // 名字
                  StructuredName.MIDDLE_NAME,                    // 中间名
                  StructuredName.FAMILY_NAME,                    // 姓氏
                  StructuredName.PREFIX,                         // 称谓前缀
                  StructuredName.SUFFIX,                         // 称谓后缀
                  CommonDataKinds.Note.NOTE,                     // 备注
                  Phone.NUMBER,                                  // 电话号码
                  Phone.TYPE,                                    // 电话类型
                  Phone.LABEL,                                   // 电话标签
                  Email.DATA,                                    // 邮箱数据
                  Email.ADDRESS,                                 // 邮箱地址
                  Email.TYPE,                                    // 邮箱类型
                  Email.LABEL,                                   // 邮箱标签
                  Organization.COMPANY,                          // 公司
                  Organization.TITLE,                            // 职位
                  StructuredPostal.FORMATTED_ADDRESS,            // 格式化地址
                  StructuredPostal.TYPE,                         // 地址类型
                  StructuredPostal.LABEL,                        // 地址标签
                  StructuredPostal.STREET,                       // 街道
                  StructuredPostal.POBOX,                        // 邮政信箱
                  StructuredPostal.NEIGHBORHOOD,                 // 社区/街区
                  StructuredPostal.CITY,                         // 城市
                  StructuredPostal.REGION,                       // 区域/州/省
                  StructuredPostal.POSTCODE,                     // 邮政编码
                  StructuredPostal.COUNTRY,                      // 国家
          };

  /**
   * 查询联系人列表
   * @param callMethod 调用的方法名（用于日志和错误处理）
   * @param query 搜索查询字符串
   * @param withThumbnails 是否包含缩略图
   * @param photoHighResolution 是否使用高分辨率照片
   * @param orderByGivenName 是否按名字排序
   * @param localizedLabels 是否使用本地化标签
   * @param result 结果处理器
   */
  @TargetApi(Build.VERSION_CODES.ECLAIR)
  private void getContacts(String callMethod, String query, boolean withThumbnails, boolean photoHighResolution, boolean orderByGivenName, boolean localizedLabels, Result result) {
    // 创建异步任务并在线程池中执行
    // 最后一个参数false表示这是普通查询，不是电话号码或邮箱查询
    new GetContactsTask(callMethod, result, withThumbnails, photoHighResolution, orderByGivenName, localizedLabels).executeOnExecutor(executor, query, false);
  }

  /**
   * 根据电话号码查询联系人
   * @param callMethod 调用的方法名
   * @param phone 电话号码
   * @param withThumbnails 是否包含缩略图
   * @param photoHighResolution 是否使用高分辨率照片
   * @param orderByGivenName 是否按名字排序
   * @param localizedLabels 是否使用本地化标签
   * @param result 结果处理器
   */
  private void getContactsForPhone(String callMethod, String phone, boolean withThumbnails, boolean photoHighResolution, boolean orderByGivenName, boolean localizedLabels, Result result) {
    // 创建异步任务并在线程池中执行
    // 最后一个参数true表示这是电话号码查询
    new GetContactsTask(callMethod, result, withThumbnails, photoHighResolution, orderByGivenName, localizedLabels).executeOnExecutor(executor, phone, true);
  }

  /**
   * 根据邮箱地址查询联系人
   * @param callMethod 调用的方法名
   * @param email 邮箱地址
   * @param withThumbnails 是否包含缩略图
   * @param photoHighResolution 是否使用高分辨率照片
   * @param orderByGivenName 是否按名字排序
   * @param localizedLabels 是否使用本地化标签
   * @param result 结果处理器
   */
  private void getContactsForEmail(String callMethod, String email, boolean withThumbnails, boolean photoHighResolution, boolean orderByGivenName, boolean localizedLabels, Result result) {
    // 创建异步任务并在线程池中执行
    // 最后一个参数true表示这是邮箱查询
    new GetContactsTask(callMethod, result, withThumbnails, photoHighResolution, orderByGivenName, localizedLabels).executeOnExecutor(executor, email, true);
  }

  /**
   * 当插件附加到Activity时调用
   * @param binding Activity插件绑定
   */
  @Override
  public void onAttachedToActivity(ActivityPluginBinding binding) {
    // 检查代理是否为新版ContactServiceDelegate类型
    if (delegate instanceof  ContactServiceDelegate) {
      // 将代理与Activity绑定
      ((ContactServiceDelegate) delegate).bindToActivity(binding);
    }
  }

  /**
   * 当Activity配置发生变化（如屏幕旋转）导致Activity重建前调用
   * 用于在Activity重建前清理绑定
   */
  @Override
  public void onDetachedFromActivityForConfigChanges() {
    if (delegate instanceof ContactServiceDelegate) {
      // 解除代理与Activity的绑定
      ((ContactServiceDelegate) delegate).unbindActivity();
    }
  }

  /**
   * 当Activity配置变化后重新附加到插件时调用
   * @param binding Activity插件绑定
   */
  @Override
  public void onReattachedToActivityForConfigChanges(ActivityPluginBinding binding) {
    if (delegate instanceof  ContactServiceDelegate) {
      // 重新将代理与Activity绑定
      ((ContactServiceDelegate) delegate).bindToActivity(binding);
    }
  }

  /**
   * 当插件与Activity分离时调用
   * 通常发生在Activity销毁时
   */
  @Override
  public void onDetachedFromActivity() {
    if (delegate instanceof ContactServiceDelegate) {
      // 解除代理与Activity的绑定
      ((ContactServiceDelegate) delegate).unbindActivity();
    }
  }

  /**
   * 联系人服务代理的基类
   * 处理需要Activity上下文的操作，如打开联系人表单、选择器等
   */
  private class BaseContactsServiceDelegate implements PluginRegistry.ActivityResultListener {
    // 请求代码常量定义
    private static final int REQUEST_OPEN_CONTACT_FORM = 52941;        // 打开新建联系人表单
    private static final int REQUEST_OPEN_EXISTING_CONTACT = 52942;    // 打开现有联系人编辑
    private static final int REQUEST_OPEN_CONTACT_PICKER = 52943;      // 打开联系人选择器

    // 结果处理器，用于返回结果给Flutter端
    private Result result;
    // 是否使用本地化标签的标志
    private boolean localizedLabels;

    /**
     * 设置结果处理器
     * @param result 结果处理器
     */
    void setResult(Result result) {
      this.result = result;
    }

    /**
     * 设置是否使用本地化标签
     * @param localizedLabels 是否使用本地化标签
     */
    void setLocalizedLabels(boolean localizedLabels) {
      this.localizedLabels = localizedLabels;
    }

    /**
     * 完成操作并返回结果
     * @param resultValue 要返回的结果值
     */
    void finishWithResult(Object resultValue) {
      // 确保result不为null，避免空指针异常
      if(this.result != null) {
        // 返回成功结果
        this.result.success(resultValue);
        // 清空result引用，避免内存泄漏
        this.result = null;
      }
    }

    /**
     * 处理Activity返回的结果
     * 当用户在打开的联系人编辑页面或选择器中完成操作后会回调此方法
     * @param requestCode 请求代码，标识是哪种操作
     * @param resultCode 结果代码，标识操作成功或取消
     * @param intent 包含结果数据的Intent对象
     * @return 是否处理了这个结果
     */
    @Override
    public boolean onActivityResult(int requestCode, int resultCode, Intent intent) {
      // 处理打开现有联系人编辑或新建联系人表单的结果
      if(requestCode == REQUEST_OPEN_EXISTING_CONTACT || requestCode == REQUEST_OPEN_CONTACT_FORM) {
        try {
          // 获取联系人URI
          Uri ur = intent.getData();
          // 从URI中提取联系人ID并获取联系人详情
          finishWithResult(getContactByIdentifier(ur.getLastPathSegment()));
        } catch (NullPointerException e) {
          // 如果出现空指针异常（可能用户取消了操作），返回取消状态
          finishWithResult(FORM_OPERATION_CANCELED);
        }
        return true;
      }

      // 处理联系人选择器的结果
      if (requestCode == REQUEST_OPEN_CONTACT_PICKER) {
        // 如果用户取消了选择
        if (resultCode == RESULT_CANCELED) {
          finishWithResult(FORM_OPERATION_CANCELED);
          return true;
        }
        // 获取选择的联系人URI
        Uri contactUri = intent.getData();
        // 查询联系人信息
        Cursor cursor = contentResolver.query(contactUri, null, null, null, null);
        if (cursor.moveToFirst()) {
          // 获取联系人ID
          String id = contactUri.getLastPathSegment();
          // 查询联系人详细信息
          getContacts("openDeviceContactPicker", id, false, false, false, localizedLabels, this.result);
        } else {
          // 查询失败，记录错误
          Log.e(LOG_TAG, "onActivityResult - cursor.moveToFirst() returns false");
          finishWithResult(FORM_OPERATION_CANCELED);
        }
        // 关闭游标，避免资源泄漏
        cursor.close();
        return true;
      }

      // 未处理的请求代码，返回表单无法打开的状态
      finishWithResult(FORM_COULD_NOT_BE_OPEN);
      return false;
    }

    /**
     * 打开现有联系人进行编辑
     * @param contact 要编辑的联系人对象
     */
    void openExistingContact(Contact contact) {
      String identifier = contact.identifier;
      try {
        // 检查联系人是否存在
        HashMap contactMapFromDevice = getContactByIdentifier(identifier);
        // 联系人存在检查
        if(contactMapFromDevice != null) {
          // 构建联系人URI
          Uri uri = Uri.withAppendedPath(ContactsContract.Contacts.CONTENT_URI, identifier);
          // 创建编辑联系人的Intent
          Intent intent = new Intent(Intent.ACTION_EDIT);
          // 设置数据类型
          intent.setDataAndType(uri, ContactsContract.Contacts.CONTENT_ITEM_TYPE);
          // 设置保存完成后自动关闭Activity
          intent.putExtra("finishActivityOnSaveCompleted", true);
          // 启动Intent
          startIntent(intent, REQUEST_OPEN_EXISTING_CONTACT);
        } else {
          // 联系人不存在
          finishWithResult(FORM_COULD_NOT_BE_OPEN);
        }
      } catch(Exception e) {
        // 发生异常
        finishWithResult(FORM_COULD_NOT_BE_OPEN);
      }
    }

    /**
     * 打开新建联系人表单
     */
    void openContactForm() {
      try {
        // 创建插入联系人的Intent
        Intent intent = new Intent(Intent.ACTION_INSERT, ContactsContract.Contacts.CONTENT_URI);
        // 设置保存完成后自动关闭Activity
        intent.putExtra("finishActivityOnSaveCompleted", true);
        // 启动Intent
        startIntent(intent, REQUEST_OPEN_CONTACT_FORM);
      } catch(Exception e) {
        // 发生异常但没有处理
      }
    }

    /**
     * 打开联系人选择器
     */
    void openContactPicker() {
      // 创建联系人选择器Intent
      Intent intent = new Intent(Intent.ACTION_PICK);
      // 设置类型为联系人类型
      intent.setType(ContactsContract.Contacts.CONTENT_TYPE);
      // 启动Intent
      startIntent(intent, REQUEST_OPEN_CONTACT_PICKER);
    }

    /**
     * 启动Intent的抽象方法
     * 由具体的子类实现
     * @param intent 要启动的Intent
     * @param request 请求代码
     */
    void startIntent(Intent intent, int request) {
      // 基类中为空实现，由子类覆盖
    }

    /**
     * 通过联系人ID获取联系人详情
     * @param identifier 联系人ID
     * @return 联系人信息的HashMap
     */
    HashMap getContactByIdentifier(String identifier) {
      ArrayList<Contact> matchingContacts;
      {
        // 查询联系人数据库
        Cursor cursor = contentResolver.query(
                ContactsContract.Data.CONTENT_URI, PROJECTION,
                ContactsContract.RawContacts.CONTACT_ID + " = ?",
                new String[]{identifier},
                null
        );
        try {
          // 从游标中解析联系人数据
          matchingContacts = getContactsFrom(cursor, localizedLabels);
        } finally {
          // 确保游标被关闭
          if(cursor != null) {
            cursor.close();
          }
        }
      }
      // 如果找到匹配的联系人，返回其Map表示
      if(matchingContacts.size() > 0) {
        return matchingContacts.iterator().next().toMap();
      }
      // 未找到联系人，返回null
      return null;
    }
  }

  /**
   * 打开设备的联系人选择器
   * @param result 结果处理器
   * @param localizedLabels 是否使用本地化标签
   */
  private void openDeviceContactPicker(Result result, boolean localizedLabels) {
    // 检查代理是否存在
    if (delegate != null) {
      // 设置结果处理器和本地化标签标志
      delegate.setResult(result);
      delegate.setLocalizedLabels(localizedLabels);
      // 打开联系人选择器
      delegate.openContactPicker();
    } else {
      // 代理不存在，返回表单无法打开的状态
      result.success(FORM_COULD_NOT_BE_OPEN);
    }
  }

  /**
   * 旧版联系人服务代理实现
   * 用于兼容旧版Flutter插件架构
   */
  private class ContactServiceDelegateOld extends BaseContactsServiceDelegate {
    // 插件注册器，用于获取Activity和Context
    private final PluginRegistry.Registrar registrar;

    /**
     * 构造方法
     * @param registrar 插件注册器
     */
    ContactServiceDelegateOld(PluginRegistry.Registrar registrar) {
      this.registrar = registrar;
      // 将自身注册为Activity结果监听器
      registrar.addActivityResultListener(this);
    }

    /**
     * 实现启动Intent的方法
     * @param intent 要启动的Intent
     * @param request 请求代码
     */
    @Override
    void startIntent(Intent intent, int request) {
      // 如果有Activity上下文，使用Activity启动
      if (registrar.activity() != null) {
        registrar.activity().startActivityForResult(intent, request);
      } else {
        // 否则使用应用上下文启动
        registrar.context().startActivity(intent);
      }
    }
  }

  /**
   * 新版联系人服务代理实现
   * 用于兼容新版Flutter插件架构
   */
  private class ContactServiceDelegate extends BaseContactsServiceDelegate {
    // 应用上下文，用于启动Intent
    private final Context context;
    // Activity插件绑定，用于获取Activity和注册结果监听器
    private ActivityPluginBinding activityPluginBinding;

    /**
     * 构造方法
     * @param context 应用上下文
     */
    ContactServiceDelegate(Context context) {
      this.context = context;
    }

    /**
     * 将代理与Activity绑定
     * @param activityPluginBinding Activity插件绑定
     */
    void bindToActivity(ActivityPluginBinding activityPluginBinding) {
      this.activityPluginBinding = activityPluginBinding;
      // 将自身注册为Activity结果监听器
      this.activityPluginBinding.addActivityResultListener(this);
    }

    /**
     * 解除与Activity的绑定
     */
    void unbindActivity() {
      // 移除Activity结果监听器
      this.activityPluginBinding.removeActivityResultListener(this);
      // 清空引用，避免内存泄漏
      this.activityPluginBinding = null;
    }

    /**
     * 实现启动Intent的方法
     * @param intent 要启动的Intent
     * @param request 请求代码
     */
    @Override
    void startIntent(Intent intent, int request) {
      // 如果已绑定Activity
      if (this.activityPluginBinding != null) {
        // 检查是否有应用可以处理这个Intent
        if (intent.resolveActivity(context.getPackageManager()) != null) {
          // 使用Activity启动Intent
          activityPluginBinding.getActivity().startActivityForResult(intent, request);
        } else {
          // 没有应用可以处理这个Intent
          finishWithResult(FORM_COULD_NOT_BE_OPEN);
        }
      } else {
        // 未绑定Activity，使用应用上下文启动
        context.startActivity(intent);
      }
    }
  }

  /**
   * 异步获取联系人任务
   * 用于在后台线程中执行耗时的联系人查询操作
   */
  @TargetApi(Build.VERSION_CODES.CUPCAKE)
  private class GetContactsTask extends AsyncTask<Object, Void, ArrayList<HashMap>> {

    // 调用方法名
    private String callMethod;
    // 结果处理器
    private Result getContactResult;
    // 是否包含缩略图
    private boolean withThumbnails;
    // 是否使用高分辨率照片
    private boolean photoHighResolution;
    // 是否按名字排序
    private boolean orderByGivenName;
    // 是否使用本地化标签
    private boolean localizedLabels;

    /**
     * 构造方法
     * @param callMethod 调用的方法名
     * @param result 结果处理器
     * @param withThumbnails 是否包含缩略图
     * @param photoHighResolution 是否使用高分辨率照片
     * @param orderByGivenName 是否按名字排序
     * @param localizedLabels 是否使用本地化标签
     */
    public GetContactsTask(String callMethod, Result result, boolean withThumbnails, boolean photoHighResolution, boolean orderByGivenName, boolean localizedLabels) {
      this.callMethod = callMethod;
      this.getContactResult = result;
      this.withThumbnails = withThumbnails;
      this.photoHighResolution = photoHighResolution;
      this.orderByGivenName = orderByGivenName;
      this.localizedLabels = localizedLabels;
    }

    /**
     * 在后台线程中执行联系人查询操作
     * @param params 参数数组，包含查询条件等
     * @return 联系人信息的HashMap列表
     */
    @TargetApi(Build.VERSION_CODES.ECLAIR)
    protected ArrayList<HashMap> doInBackground(Object... params) {
      ArrayList<Contact> contacts;
      // 根据调用的方法选择不同的查询方式
      switch (callMethod) {
        case "openDeviceContactPicker":
          // 从联系人选择器打开的联系人
          contacts = getContactsFrom(getCursor(null, (String) params[0]), localizedLabels);
          break;
        case "getContacts":
          // 普通联系人查询
          contacts = getContactsFrom(getCursor((String) params[0], null), localizedLabels);
          break;
        case "getContactsForPhone":
          // 按电话号码查询
          contacts = getContactsFrom(getCursorForPhone(((String) params[0])), localizedLabels);
          break;
        case "getContactsForEmail":
          // 按邮箱地址查询
          contacts = getContactsFrom(getCursorForEmail(((String) params[0])), localizedLabels);
          break;
        default:
          // 未知方法，返回null
          return null;
      }

      // 如果需要缩略图
      if (withThumbnails) {
        for(Contact c : contacts){
          // 加载联系人照片
          final byte[] avatar = loadContactPhotoHighRes(
                  c.identifier, photoHighResolution, contentResolver);
          if (avatar != null) {
            c.avatar = avatar;
          } else {
            // 为了向后兼容，返回空字节数组而不是null
            c.avatar = new byte[0];
          }
        }
      }

      // 如果需要按名字排序
      if (orderByGivenName)
      {
        // 创建比较器
        Comparator<Contact> compareByGivenName = new Comparator<Contact>() {
          @Override
          public int compare(Contact contactA, Contact contactB) {
            // 使用Contact类的compareTo方法进行比较
            return contactA.compareTo(contactB);
          }
        };
        // 排序联系人列表
        Collections.sort(contacts, compareByGivenName);
      }

      // 将联系人列表转换为Map列表
      ArrayList<HashMap> contactMaps = new ArrayList<>();
      for(Contact c : contacts){
        contactMaps.add(c.toMap());
      }

      return contactMaps;
    }

    /**
     * 后台任务完成后在主线程中执行
     * @param result 联系人信息的HashMap列表
     */
    protected void onPostExecute(ArrayList<HashMap> result) {
      if (result == null) {
        // 任务未完成（方法未实现或出错）
        getContactResult.notImplemented();
      } else {
        // 成功完成任务，返回结果
        getContactResult.success(result);
      }
    }
  }


  /**
   * 构建联系人查询的游标
   * 用于普通联系人查询或按ID查询
   * @param query 搜索查询字符串
   * @param rawContactId 联系人ID
   * @return 查询结果游标
   */
  private Cursor getCursor(String query, String rawContactId) {
    // 构建选择条件，包含各种数据类型的联系人信息
    String selection = "(" + ContactsContract.Data.MIMETYPE + "=? OR " + ContactsContract.Data.MIMETYPE + "=? OR "
            + ContactsContract.Data.MIMETYPE + "=? OR " + ContactsContract.Data.MIMETYPE + "=? OR "
            + ContactsContract.Data.MIMETYPE + "=? OR " + ContactsContract.Data.MIMETYPE + "=? OR "
            + ContactsContract.Data.MIMETYPE + "=? OR " + ContactsContract.RawContacts.ACCOUNT_TYPE + "=?" + ")";

    // 构建选择参数，包含各种内容类型
    ArrayList<String> selectionArgs = new ArrayList<>(Arrays.asList(
            CommonDataKinds.Note.CONTENT_ITEM_TYPE,        // 备注类型
            Email.CONTENT_ITEM_TYPE,                      // 邮箱类型
            Phone.CONTENT_ITEM_TYPE,                      // 电话类型
            StructuredName.CONTENT_ITEM_TYPE,             // 姓名类型
            Organization.CONTENT_ITEM_TYPE,               // 组织类型
            StructuredPostal.CONTENT_ITEM_TYPE,           // 地址类型
            CommonDataKinds.Event.CONTENT_ITEM_TYPE,      // 事件类型
            ContactsContract.RawContacts.ACCOUNT_TYPE     // 账户类型
    ));

    // 如果有搜索查询
    if (query != null) {
      // 重置选择参数
      selectionArgs = new ArrayList<>();
      // 添加查询条件，使用LIKE操作符进行前缀匹配
      selectionArgs.add(query + "%");
      // 按显示名称搜索
      selection = ContactsContract.Contacts.DISPLAY_NAME_PRIMARY + " LIKE ?";
    }

    // 如果有联系人ID
    if (rawContactId != null) {
      // 添加联系人ID作为参数
      selectionArgs.add(rawContactId);
      // 添加ID过滤条件
      selection += " AND " + ContactsContract.Data.CONTACT_ID + " =?";
    }

    // 执行查询并返回游标
    return contentResolver.query(
            ContactsContract.Data.CONTENT_URI,  // 查询的数据表URI
            PROJECTION,                         // 要返回的列
            selection,                          // 查询条件
            selectionArgs.toArray(new String[selectionArgs.size()]), // 查询参数
            null                                // 排序方式
    );
  }

  /**
   * 根据电话号码构建查询游标 - 通过电话号码查找对应的联系人
   * 这是一个两步查询过程：先通过电话号码找到联系人ID，再通过ID获取详细信息
   * @param phone 电话号码 - 要查找的联系人电话号码
   * @return 查询结果游标 - 包含找到的联系人详细信息
   */
  private Cursor getCursorForPhone(String phone) {
    // 检查电话号码是否为空，为空则直接返回null
    if (phone.isEmpty())
      return null;

    // 构建电话号码查询URI - 使用系统提供的PhoneLookup来快速查找电话号码对应的联系人
    // Uri.encode(phone)确保电话号码中的特殊字符被正确编码
    Uri uri = Uri.withAppendedPath(ContactsContract.PhoneLookup.CONTENT_FILTER_URI, Uri.encode(phone));
    // 只查询ID列 - 因为这一步只需要找到联系人ID
    String[] projection = new String[]{BaseColumns._ID};

    // 存储找到的联系人ID的集合
    ArrayList<String> contactIds = new ArrayList<>();
    // 执行查询 - 使用contentResolver查询包含该电话号码的联系人
    Cursor phoneCursor = contentResolver.query(uri, projection, null, null, null);
    // 遍历查询结果
    while (phoneCursor != null && phoneCursor.moveToNext()){
      // 获取并添加联系人ID到列表中
      contactIds.add(phoneCursor.getString(phoneCursor.getColumnIndex(BaseColumns._ID)));
    }
    // 关闭游标 - 避免资源泄露
    if (phoneCursor!= null)
      phoneCursor.close();

    // 如果找到至少一个联系人
    if (!contactIds.isEmpty()) {
      // 将ID列表转换为SQL IN子句格式 - [1,2,3] -> (1,2,3)
      String contactIdsListString = contactIds.toString().replace("[", "(").replace("]", ")");
      // 构建查询条件 - WHERE CONTACT_ID IN (1,2,3)
      String contactSelection = ContactsContract.Data.CONTACT_ID + " IN " + contactIdsListString;
      // 查询这些联系人的详细信息 - 使用之前定义的完整PROJECTION获取所有需要的字段
      return contentResolver.query(ContactsContract.Data.CONTENT_URI, PROJECTION, contactSelection, null, null);
    }

    // 未找到联系人，返回null
    return null;
  }

  /**
   * 根据邮箱地址构建查询游标 - 通过邮箱地址查找对应的联系人
   * @param email 邮箱地址 - 要查找的联系人邮箱
   * @return 查询结果游标 - 包含找到的联系人详细信息
   */
  private Cursor getCursorForEmail(String email) {
    // 检查邮箱是否为空，为空则直接返回null
    if (email.isEmpty())
      return null;

    // 构建选择参数 - 使用%通配符进行模糊匹配，这样可以匹配包含该邮箱的任何联系人
    // 例如：搜索"example"会匹配"example@domain.com"
    ArrayList<String> selectionArgs = new ArrayList<>(Arrays.asList("%" + email + "%"));

    // 构建查询条件 - WHERE EMAIL_ADDRESS LIKE ?
    String selection = Email.ADDRESS + " LIKE ?";

    // 执行查询并返回游标 - 直接在ContactsContract.Data表中查询
    // 将List转换为数组作为selectionArgs参数
    return contentResolver.query(ContactsContract.Data.CONTENT_URI, PROJECTION, selection, selectionArgs.toArray(new String[selectionArgs.size()]), null);
  }

  /**
   * 从查询游标中构建联系人列表 - 这是数据解析的核心方法
   * 将数据库返回的原始记录转换为有组织的Contact对象列表
   * @param cursor 查询结果游标 - 包含从数据库查询得到的原始联系人记录
   * @param localizedLabels 是否使用本地化标签 - true使用本地语言（如中文）的标签，false使用默认英文标签
   * @return 联系人列表 - 包含所有解析后的Contact对象
   */
  private ArrayList<Contact> getContactsFrom(Cursor cursor, boolean localizedLabels) {
    // 使用LinkedHashMap存储联系人，确保插入顺序与查询顺序一致
    // key是contactId，value是Contact对象
    HashMap<String, Contact> map = new LinkedHashMap<>();

    // 遍历游标中的每一行数据
    while (cursor != null && cursor.moveToNext()) {
      // 获取联系人ID
      int columnIndex = cursor.getColumnIndex(ContactsContract.Data.CONTACT_ID);
      String contactId = cursor.getString(columnIndex);

      // 如果这是第一次遇到这个联系人ID，创建新的Contact对象
      if (!map.containsKey(contactId)) {
        map.put(contactId, new Contact(contactId));
      }
      // 获取当前联系人对象
      Contact contact = map.get(contactId);

      // 获取当前行数据的类型（mime类型）
      String mimeType = cursor.getString(cursor.getColumnIndex(ContactsContract.Data.MIMETYPE));

      // 设置联系人的基本信息
      contact.displayName = cursor.getString(cursor.getColumnIndex(ContactsContract.Contacts.DISPLAY_NAME));
      contact.androidAccountType = cursor.getString(cursor.getColumnIndex(ContactsContract.RawContacts.ACCOUNT_TYPE));
      contact.androidAccountName = cursor.getString(cursor.getColumnIndex(ContactsContract.RawContacts.ACCOUNT_NAME));

      // 根据数据类型(mimeType)处理不同类型的联系人数据
      // 全名信息（姓、名、中间名等）
      if (mimeType.equals(CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE)) {
        contact.givenName = cursor.getString(cursor.getColumnIndex(StructuredName.GIVEN_NAME));
        contact.middleName = cursor.getString(cursor.getColumnIndex(StructuredName.MIDDLE_NAME));
        contact.familyName = cursor.getString(cursor.getColumnIndex(StructuredName.FAMILY_NAME));
        contact.prefix = cursor.getString(cursor.getColumnIndex(StructuredName.PREFIX));
        contact.suffix = cursor.getString(cursor.getColumnIndex(StructuredName.SUFFIX));
      }
      // 备注信息
      else if (mimeType.equals(CommonDataKinds.Note.CONTENT_ITEM_TYPE)) {
        contact.note = cursor.getString(cursor.getColumnIndex(CommonDataKinds.Note.NOTE));
      }
      // 电话号码信息
      else if (mimeType.equals(CommonDataKinds.Phone.CONTENT_ITEM_TYPE)){
        String phoneNumber = cursor.getString(cursor.getColumnIndex(Phone.NUMBER));
        // 检查电话号码是否为空
        if (!TextUtils.isEmpty(phoneNumber)){
          // 获取电话号码类型（如手机、家庭、工作等）
          int type = cursor.getInt(cursor.getColumnIndex(Phone.TYPE));
          // 获取本地化的标签（如"手机"、"家庭电话"等）
          String label = Item.getPhoneLabel(resources, type, cursor, localizedLabels);
          // 添加到联系人的电话号码列表中
          contact.phones.add(new Item(label, phoneNumber, type));
        }
      }
      // 邮箱地址信息
      else if (mimeType.equals(CommonDataKinds.Email.CONTENT_ITEM_TYPE)) {
        String email = cursor.getString(cursor.getColumnIndex(Email.ADDRESS));
        int type = cursor.getInt(cursor.getColumnIndex(Email.TYPE));
        // 检查邮箱地址是否为空
        if (!TextUtils.isEmpty(email)) {
          // 获取本地化的邮箱标签（如"工作邮箱"、"个人邮箱"等）
          String label = Item.getEmailLabel(resources, type, cursor, localizedLabels);
          // 添加到联系人的邮箱列表中
          contact.emails.add(new Item(label, email, type));
        }
      }
      // 工作信息（公司、职位）
      else if (mimeType.equals(CommonDataKinds.Organization.CONTENT_ITEM_TYPE)) {
        contact.company = cursor.getString(cursor.getColumnIndex(Organization.COMPANY));
        contact.jobTitle = cursor.getString(cursor.getColumnIndex(Organization.TITLE));
      }
      // 地址信息
      else if (mimeType.equals(CommonDataKinds.StructuredPostal.CONTENT_ITEM_TYPE)) {
        int type = cursor.getInt(cursor.getColumnIndex(StructuredPostal.TYPE));
        // 获取本地化的地址标签（如"家庭地址"、"工作地址"等）
        String label = PostalAddress.getLabel(resources, type, cursor, localizedLabels);
        // 获取地址各部分信息
        String street = cursor.getString(cursor.getColumnIndex(StructuredPostal.STREET));
        String city = cursor.getString(cursor.getColumnIndex(StructuredPostal.CITY));
        String postcode = cursor.getString(cursor.getColumnIndex(StructuredPostal.POSTCODE));
        String region = cursor.getString(cursor.getColumnIndex(StructuredPostal.REGION));
        String country = cursor.getString(cursor.getColumnIndex(StructuredPostal.COUNTRY));
        // 创建PostalAddress对象并添加到联系人的地址列表中
        contact.postalAddresses.add(new PostalAddress(label, street, city, postcode, region, country, type));
      }
      // 生日信息
      else if (mimeType.equals(CommonDataKinds.Event.CONTENT_ITEM_TYPE)) {
        int eventType = cursor.getInt(cursor.getColumnIndex(CommonDataKinds.Event.TYPE));
        // 只处理生日类型的事件
        if (eventType == CommonDataKinds.Event.TYPE_BIRTHDAY) {
          contact.birthday = cursor.getString(cursor.getColumnIndex(CommonDataKinds.Event.START_DATE));
        }
      }
    }

    // 关闭游标，避免资源泄露
    if(cursor != null)
      cursor.close();

    // 将map中的Contact对象转换为ArrayList并返回
    return new ArrayList<>(map.values());
  }

  /**
   * 为联系人设置头像数据（如果可用）
   * 从联系人数据库中查询并加载联系人头像
   * @param contact 要设置头像的联系人对象
   */
  private void setAvatarDataForContactIfAvailable(Contact contact) {
    // 构建联系人的URI - 通过联系人ID构建URI
    Uri contactUri = ContentUris.withAppendedId(ContactsContract.Contacts.CONTENT_URI, Integer.parseInt(contact.identifier));

    // 构建照片的URI - 在联系人URI后追加照片目录
    Uri photoUri = Uri.withAppendedPath(contactUri, ContactsContract.Contacts.Photo.CONTENT_DIRECTORY);

    // 查询联系人头像 - 只查询照片数据列
    Cursor avatarCursor = contentResolver.query(photoUri,
            new String[] {ContactsContract.Contacts.Photo.PHOTO}, null, null, null);

    // 检查是否找到头像数据
    if (avatarCursor != null && avatarCursor.moveToFirst()) {
      // 获取头像的二进制数据（byte[]类型）
      byte[] avatar = avatarCursor.getBlob(0);
      // 设置到联系人对象中
      contact.avatar = avatar;
    }

    // 关闭游标，避免资源泄露
    if (avatarCursor != null) {
      avatarCursor.close();
    }
  }

  /**
   * 获取联系人头像的方法 - 异步执行
   * @param contact 要获取头像的联系人
   * @param highRes 是否获取高清头像
   * @param result 结果处理器，用于回调处理完成的结果
   */
  private void getAvatar(final Contact contact, final boolean highRes,
                         final Result result) {
    // 创建异步任务并在线程池中执行
    // 使用executor确保在后台线程执行，避免阻塞UI线程
    new GetAvatarsTask(contact, highRes, contentResolver, result).executeOnExecutor(this.executor);
  }

  /**
   * 异步获取联系人头像的任务类
   * 继承自AsyncTask，在后台线程中执行头像加载操作
   * 泛型参数说明：
   * - 第一个Void：doInBackground不需要参数
   * - 第二个Void：不使用进度更新
   * - 第三个byte[]：返回头像的二进制数据
   */
  private static class GetAvatarsTask extends AsyncTask<Void, Void, byte[]> {
    // 要获取头像的联系人
    final Contact contact;
    // 是否获取高清头像
    final boolean highRes;
    // 用于查询联系人数据的ContentResolver
    final ContentResolver contentResolver;
    // 结果处理器，用于回调结果
    final Result result;

    /**
     * 构造方法
     * @param contact 要获取头像的联系人对象
     * @param highRes 是否获取高清头像
     * @param contentResolver 用于访问联系人数据的ContentResolver
     * @param result 结果回调处理器
     */
    GetAvatarsTask(final Contact contact, final boolean highRes,
                   final ContentResolver contentResolver, final Result result) {
      // 初始化成员变量
      this.contact = contact;
      this.highRes = highRes;
      this.contentResolver = contentResolver;
      this.result = result;
    }

    /**
     * 后台执行方法 - 在非UI线程中运行
     * @param params 无参数
     * @return 头像的二进制数据
     */
    @Override
    protected byte[] doInBackground(final Void... params) {
      // 调用loadContactPhotoHighRes方法加载联系人头像
      // 传入联系人ID、是否高清标志和ContentResolver
      return loadContactPhotoHighRes(contact.identifier, highRes, contentResolver);
    }

    /**
     * 任务完成后在UI线程执行的方法
     * @param avatar 从后台获取的头像二进制数据
     */
    @Override
    protected void onPostExecute(final byte[] avatar) {
      // 通过result回调接口通知调用者任务完成，并返回头像数据
      result.success(avatar);
    }
  }

  /**
   * 加载联系人高清头像的方法
   * @param identifier 联系人ID
   * @param photoHighResolution 是否加载高清头像
   * @param contentResolver 内容解析器，用于访问联系人数据
   * @return 头像的二进制数据，如果加载失败则返回null
   */
  private static byte[] loadContactPhotoHighRes(final String identifier,
                                                final boolean photoHighResolution, final ContentResolver contentResolver) {
    try {
      // 根据联系人ID构建URI
      final Uri uri = ContentUris.withAppendedId(ContactsContract.Contacts.CONTENT_URI, Long.parseLong(identifier));

      // 打开联系人照片输入流
      // 第三个参数决定是否加载高清头像
      final InputStream input = ContactsContract.Contacts.openContactPhotoInputStream(contentResolver, uri, photoHighResolution);

      // 如果没有找到照片，直接返回null
      if (input == null) return null;

      // 将输入流解码为Bitmap对象
      final Bitmap bitmap = BitmapFactory.decodeStream(input);
      // 关闭输入流
      input.close();

      // 创建字节数组输出流，用于将Bitmap转换为字节数组
      final ByteArrayOutputStream stream = new ByteArrayOutputStream();
      // 将Bitmap压缩为PNG格式，质量为100（最高质量）
      bitmap.compress(Bitmap.CompressFormat.PNG, 100, stream);
      // 获取字节数组
      final byte[] bytes = stream.toByteArray();
      // 关闭输出流
      stream.close();

      return bytes;
    } catch (final IOException ex){
      // 记录错误日志
      Log.e(LOG_TAG, ex.getMessage());
      return null;
    }
  }

  /**
   * 添加新联系人到系统联系人数据库
   * @param contact 要添加的联系人对象
   * @return 是否添加成功
   */
  private boolean addContact(Contact contact){
    // 创建操作列表，用于批量执行ContentProvider操作
    // ContentProviderOperation是Android中用于原子性地执行多个数据操作的机制
    ArrayList<ContentProviderOperation> ops = new ArrayList<>();

    // 第一步：创建RawContact记录
    // RawContact是联系人的原始数据记录，不与任何账号关联（ACCOUNT_TYPE和ACCOUNT_NAME为null）
    ContentProviderOperation.Builder op = ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI)
            .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, null) // 无账号类型
            .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, null); // 无账号名称
    // 将操作添加到列表
    ops.add(op.build());

    // 第二步：添加联系人名称信息
    // withValueBackReference表示引用前面操作的结果（这里引用第一步创建的RawContact的ID）
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // 引用第一个操作的结果
            .withValue(ContactsContract.Data.MIMETYPE, CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE) // 数据类型为结构化名称
            .withValue(StructuredName.GIVEN_NAME, contact.givenName) // 名
            .withValue(StructuredName.MIDDLE_NAME, contact.middleName) // 中间名
            .withValue(StructuredName.FAMILY_NAME, contact.familyName) // 姓
            .withValue(StructuredName.PREFIX, contact.prefix) // 称谓前缀（如Mr.）
            .withValue(StructuredName.SUFFIX, contact.suffix); // 称谓后缀（如Jr.）
    ops.add(op.build());

    // 第三步：添加联系人备注信息
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
            .withValue(ContactsContract.Data.MIMETYPE, CommonDataKinds.Note.CONTENT_ITEM_TYPE) // 数据类型为备注
            .withValue(CommonDataKinds.Note.NOTE, contact.note); // 备注内容
    ops.add(op.build());

    // 第四步：添加联系人工作信息
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
            .withValue(ContactsContract.Data.MIMETYPE, CommonDataKinds.Organization.CONTENT_ITEM_TYPE) // 数据类型为组织/工作信息
            .withValue(Organization.COMPANY, contact.company) // 公司名称
            .withValue(Organization.TITLE, contact.jobTitle); // 职位
    ops.add(op.build());

    // 第五步：添加联系人头像
    //Photo
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
            .withValue(ContactsContract.Data.IS_SUPER_PRIMARY, 1) // 标记为主要头像
            .withValue(ContactsContract.CommonDataKinds.Photo.PHOTO, contact.avatar) // 头像二进制数据
            .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Photo.CONTENT_ITEM_TYPE); // 数据类型为照片
    ops.add(op.build());

    // 允许在执行操作期间释放CPU资源给其他任务
    op.withYieldAllowed(true);

    // 第六步：添加联系人电话号码
    //Phones
    for(Item phone : contact.phones){ // 遍历所有电话号码
      op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
              .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
              .withValue(ContactsContract.Data.MIMETYPE, CommonDataKinds.Phone.CONTENT_ITEM_TYPE) // 数据类型为电话号码
              .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone.value); // 电话号码

      // 处理自定义类型的电话号码
      if (phone.type == ContactsContract.CommonDataKinds.Phone.TYPE_CUSTOM){
        // 设置为自定义类型
        op.withValue( ContactsContract.CommonDataKinds.Phone.TYPE, ContactsContract.CommonDataKinds.BaseTypes.TYPE_CUSTOM );
        // 设置自定义标签（如"学校电话"、"紧急联系"等）
        op.withValue(ContactsContract.CommonDataKinds.Phone.LABEL, phone.label);
      } else
        // 对于非自定义类型，直接使用预定义类型值
        op.withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phone.type);

      // 添加电话操作到操作列表
      ops.add(op.build());
    }

    // 第七步：添加联系人邮箱地址
    //Emails
    for (Item email : contact.emails) { // 遍历所有邮箱地址
      op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
              .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // 引用RawContact ID
              .withValue(ContactsContract.Data.MIMETYPE, CommonDataKinds.Email.CONTENT_ITEM_TYPE) // 数据类型为邮箱
              .withValue(CommonDataKinds.Email.ADDRESS, email.value) // 邮箱地址
              .withValue(CommonDataKinds.Email.TYPE, email.type); // 邮箱类型（工作、个人等）
      ops.add(op.build()); // 添加到操作列表
    }
    // 第八步：添加联系人地址信息
    //Postal addresses
    for (PostalAddress address : contact.postalAddresses) { // 遍历所有地址
      op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
              .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // 引用RawContact ID
              .withValue(ContactsContract.Data.MIMETYPE, CommonDataKinds.StructuredPostal.CONTENT_ITEM_TYPE) // 数据类型为结构化地址
              .withValue(CommonDataKinds.StructuredPostal.TYPE, address.type) // 地址类型（家庭、工作等）
              .withValue(CommonDataKinds.StructuredPostal.LABEL, address.label) // 地址标签
              .withValue(CommonDataKinds.StructuredPostal.STREET, address.street) // 街道
              .withValue(CommonDataKinds.StructuredPostal.CITY, address.city) // 城市
              .withValue(CommonDataKinds.StructuredPostal.REGION, address.region) // 区域/州
              .withValue(CommonDataKinds.StructuredPostal.POSTCODE, address.postcode) // 邮政编码
              .withValue(CommonDataKinds.StructuredPostal.COUNTRY, address.country); // 国家
      ops.add(op.build()); // 添加到操作列表
    }

    // 第九步：添加联系人生日信息
    // Birthday
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // 引用RawContact ID
            .withValue(ContactsContract.Data.MIMETYPE, CommonDataKinds.Event.CONTENT_ITEM_TYPE) // 数据类型为事件
            .withValue(CommonDataKinds.Event.TYPE, CommonDataKinds.Event.TYPE_BIRTHDAY) // 事件类型为生日
            .withValue(CommonDataKinds.Event.START_DATE, contact.birthday); // 生日日期
    ops.add(op.build()); // 添加到操作列表

    // 执行所有操作
    try {
      // 批量应用所有ContentProvider操作
      // 这种批量操作是原子性的，要么全部成功，要么全部失败
      contentResolver.applyBatch(ContactsContract.AUTHORITY, ops);
      return true; // 添加成功
    } catch (Exception e) {
      // 发生任何异常都视为添加失败
      return false;
    }
  }

  /**
   * 从系统联系人数据库中删除联系人
   * @param contact 要删除的联系人对象
   * @return 是否删除成功
   */
  private boolean deleteContact(Contact contact){
    // 创建操作列表
    ArrayList<ContentProviderOperation> ops = new ArrayList<>();

    // 创建删除操作
    // 通过联系人ID找到并删除对应的RawContact记录
    // 删除RawContact会级联删除其所有关联的数据项
    ops.add(ContentProviderOperation.newDelete(ContactsContract.RawContacts.CONTENT_URI)
            .withSelection(ContactsContract.RawContacts.CONTACT_ID + "=?",
                    new String[]{String.valueOf(contact.identifier)}) // WHERE CONTACT_ID = ?
            .build());

    try {
      // 执行删除操作
      contentResolver.applyBatch(ContactsContract.AUTHORITY, ops);
      return true; // 删除成功
    } catch (Exception e) {
      // 发生异常则删除失败
      return false;
    }
  }

  /**
   * 更新系统联系人数据库中的联系人信息
   * 更新策略是：先删除旧的详细信息，然后更新名称，最后重新添加新的详细信息
   * @param contact 要更新的联系人对象（包含最新信息）
   * @return 是否更新成功
   */
  private boolean updateContact(Contact contact) {
    // 创建操作列表
    ArrayList<ContentProviderOperation> ops = new ArrayList<>();
    ContentProviderOperation.Builder op;

    // 第一步：删除联系人的所有详细信息（保留名称信息）
    // 这种方式确保不会有旧数据残留

    // 删除组织/工作信息
    op = ContentProviderOperation.newDelete(ContactsContract.Data.CONTENT_URI)
            .withSelection(ContactsContract.Data.CONTACT_ID + "=? AND " + ContactsContract.Data.MIMETYPE + "=?",
                    new String[]{String.valueOf(contact.identifier),
                            ContactsContract.CommonDataKinds.Organization.CONTENT_ITEM_TYPE});
    ops.add(op.build());

    // 删除电话号码信息
    op = ContentProviderOperation.newDelete(ContactsContract.Data.CONTENT_URI)
            .withSelection(ContactsContract.Data.CONTACT_ID + "=? AND " + ContactsContract.Data.MIMETYPE + "=?",
                    new String[]{String.valueOf(contact.identifier),
                            ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE});
    ops.add(op.build());

    // 删除邮箱地址信息
    op = ContentProviderOperation.newDelete(ContactsContract.Data.CONTENT_URI)
            .withSelection(ContactsContract.Data.CONTACT_ID +"=? AND " + ContactsContract.Data.MIMETYPE + "=?",
                    new String[]{String.valueOf(contact.identifier),
                            ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE});
    ops.add(op.build());

    // 删除备注信息
    op = ContentProviderOperation.newDelete(ContactsContract.Data.CONTENT_URI)
            .withSelection(ContactsContract.Data.CONTACT_ID +"=? AND " + ContactsContract.Data.MIMETYPE + "=?",
                    new String[]{String.valueOf(contact.identifier),
                            ContactsContract.CommonDataKinds.Note.CONTENT_ITEM_TYPE});
    ops.add(op.build());

    // 删除地址信息
    op = ContentProviderOperation.newDelete(ContactsContract.Data.CONTENT_URI)
            .withSelection(ContactsContract.Data.CONTACT_ID + "=? AND " + ContactsContract.Data.MIMETYPE + "=?",
                    new String[]{String.valueOf(contact.identifier),
                            ContactsContract.CommonDataKinds.StructuredPostal.CONTENT_ITEM_TYPE});
    ops.add(op.build());

    // 删除头像信息
    //Photo
    op = ContentProviderOperation.newDelete(ContactsContract.Data.CONTENT_URI)
            .withSelection(ContactsContract.Data.CONTACT_ID + "=? AND " + ContactsContract.Data.MIMETYPE + "=?",
                    new String[]{String.valueOf(contact.identifier),
                            ContactsContract.CommonDataKinds.Photo.CONTENT_ITEM_TYPE});
    ops.add(op.build());

    // 第二步：更新联系人名称信息
    // Update data (name)
    op = ContentProviderOperation.newUpdate(ContactsContract.Data.CONTENT_URI)
            .withSelection(ContactsContract.Data.CONTACT_ID + "=? AND " + ContactsContract.Data.MIMETYPE + "=?",
                    new String[]{String.valueOf(contact.identifier),
                            ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE})
            .withValue(StructuredName.GIVEN_NAME, contact.givenName) // 更新名
            .withValue(StructuredName.MIDDLE_NAME, contact.middleName) // 更新中间名
            .withValue(StructuredName.FAMILY_NAME, contact.familyName) // 更新姓
            .withValue(StructuredName.PREFIX, contact.prefix) // 更新称谓前缀
            .withValue(StructuredName.SUFFIX, contact.suffix); // 更新称谓后缀
    ops.add(op.build());

    // 第三步：重新添加更新后的详细信息到联系人
    // Insert data back into contact

    // 添加工作信息
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Organization.CONTENT_ITEM_TYPE) // 数据类型为组织/工作信息
            .withValue(ContactsContract.Data.RAW_CONTACT_ID, contact.identifier) // 指定联系人ID
            .withValue(Organization.TYPE, Organization.TYPE_WORK) // 设置为工作类型
            .withValue(Organization.COMPANY, contact.company) // 公司名称
            .withValue(Organization.TITLE, contact.jobTitle); // 职位
    ops.add(op.build());

    // 添加备注信息
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Note.CONTENT_ITEM_TYPE) // 数据类型为备注
            .withValue(ContactsContract.Data.RAW_CONTACT_ID, contact.identifier) // 指定联系人ID
            .withValue(CommonDataKinds.Note.NOTE, contact.note); // 备注内容
    ops.add(op.build());

    // 添加头像信息
    //Photo
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValue(ContactsContract.Data.RAW_CONTACT_ID, contact.identifier) // 指定联系人ID
            .withValue(ContactsContract.Data.IS_SUPER_PRIMARY, 1) // 标记为主要头像
            .withValue(ContactsContract.CommonDataKinds.Photo.PHOTO, contact.avatar) // 头像数据（字节数组）
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Photo.CONTENT_ITEM_TYPE); // 数据类型为照片
    ops.add(op.build()); // 添加到操作列表


    // 添加电话号码信息
    for (Item phone : contact.phones) { // 遍历所有电话号码
      op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
              .withValue(ContactsContract.Data.MIMETYPE, CommonDataKinds.Phone.CONTENT_ITEM_TYPE) // 数据类型为电话
              .withValue(ContactsContract.Data.RAW_CONTACT_ID, contact.identifier) // 指定联系人ID
              .withValue(Phone.NUMBER, phone.value); // 电话号码

      // 处理自定义类型的电话号码
      if (phone.type == ContactsContract.CommonDataKinds.Phone.TYPE_CUSTOM){
        op.withValue( ContactsContract.CommonDataKinds.Phone.TYPE,
                ContactsContract.CommonDataKinds.BaseTypes.TYPE_CUSTOM ); // 设置为自定义类型
        op.withValue(ContactsContract.CommonDataKinds.Phone.LABEL, phone.label); // 设置自定义标签
      } else
        op.withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phone.type); // 使用预定义类型

      ops.add(op.build()); // 添加到操作列表
    }

    // 添加邮箱地址信息
    for (Item email : contact.emails) { // 遍历所有邮箱
      op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
              .withValue(ContactsContract.Data.MIMETYPE, CommonDataKinds.Email.CONTENT_ITEM_TYPE) // 数据类型为邮箱
              .withValue(ContactsContract.Data.RAW_CONTACT_ID, contact.identifier) // 指定联系人ID
              .withValue(CommonDataKinds.Email.ADDRESS, email.value) // 邮箱地址
              .withValue(CommonDataKinds.Email.TYPE, email.type); // 邮箱类型
      ops.add(op.build()); // 添加到操作列表
    }

    // 添加地址信息
    for (PostalAddress address : contact.postalAddresses) { // 遍历所有地址
      op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
              .withValue(ContactsContract.Data.MIMETYPE,
                      CommonDataKinds.StructuredPostal.CONTENT_ITEM_TYPE) // 数据类型为结构化地址
              .withValue(ContactsContract.Data.RAW_CONTACT_ID, contact.identifier) // 指定联系人ID
              .withValue(CommonDataKinds.StructuredPostal.TYPE, address.type) // 地址类型
              .withValue(CommonDataKinds.StructuredPostal.STREET, address.street) // 街道
              .withValue(CommonDataKinds.StructuredPostal.CITY, address.city) // 城市
              .withValue(CommonDataKinds.StructuredPostal.REGION, address.region) // 区域/州
              .withValue(CommonDataKinds.StructuredPostal.POSTCODE, address.postcode) // 邮政编码
              .withValue(CommonDataKinds.StructuredPostal.COUNTRY, address.country); // 国家
      ops.add(op.build()); // 添加到操作列表
    }

    // 执行所有更新操作
    try {
      // 批量应用所有ContentProvider操作
      // 这种批量操作是原子性的，要么全部成功，要么全部失败
      contentResolver.applyBatch(ContactsContract.AUTHORITY, ops);
      return true; // 更新成功
    } catch (Exception e) {
      // 记录异常信息，方便调试
      // Log exception
      Log.e("TAG", "Exception encountered while inserting contact: " );
      e.printStackTrace();
      return false; // 更新失败
    }
  }

} // ContactsServicePlugin类结束
